fix: clean up v2 templates list - #78

@brenelz

i actually don't think the with-tanstack-router one works at the moment

Honest sequence of events: my first reaction was "fair enough, I'll just delete it from the list — one line, done." But then I got curious. One "wait, why doesn't this work?" led to another. That single comment sent me down a delightful rabbit hole, and I came back with the full picture (plus two working fix approaches).

TL;DR (Summary for maintainers)

1. The with-tanstack-router template now fails SSR(HTTP 500).
   This looks like a regression from the v2 rewrite of @solidjs/start, which silently dropped the routerLoad API the template was relying on.

2. The root cause: the template calls createHandler with 3 args (the v1 API),
   but v2 only accepts 2, so the 3rd arg is silently ignored. As a result, SSR crashes because the router's internal store is never initialized.

• Two ways to fix it:
  • Approach A — Fix the template only (no solid-start changes).
  • Approach B — Restore routerLoad in solid-start (backward-compatible).

    If we don't go with Approach B, the docs should be updated to drop routerLoad from the createHandler signature in solid-docs.

3. There's a small issue independent of the above: TanStack Router officially recommends a fresh router instance per request, but the template uses a module-level singleton.
   So, Whichever approach we pick, we should also switch the template to a per-request router instance to avoid state leaking across concurrent requests.

So, the decisions needed:

(a) For the v2 template list(Choose one)

• Opt1: Remove with-tanstack-router
• Opt2: Keep it with a note pending the upstream fix.

(b) For the SSR fix itself(Choose one)

• Opt1: Approach A (template-only) + update solid-docs to drop routerLoad from createHandler
• Opt2: Approach B (restore routerLoad in solid-start) — no doc change needed.

(c) Independent of (b)

Should we also roll in the singleton-to-per-request router fix (as recommended by TanStack Router) described in the "Recommended addition" section?

• ref. Recommended-addition

Two fix approaches (both verified locally)

Both approaches produce:

• curl / → 200 with fully rendered HTML.
• curl /about → 200, zero SSR errors.

Approach A — Fix the template only (no solid-start changes)

Leverage the 2nd options parameter, which accepts an async (context) => HandlerOptions function that is awaited before rendering.

Move routerLoad logic into this options function.

Diff (entry-server.tsx):

-import { createHandler, FetchEvent, StartServer } from "@solidjs/start/server";
+import { createHandler, StartServer } from "@solidjs/start/server";
 import { createMemoryHistory } from "@tanstack/solid-router";
 import { router } from "./router";

-const routerLoad = async (event: FetchEvent) => {
-  const url = new URL(event.request.url);
-  const path = url.href.replace(url.origin, "");
-  router.update({
-    history: createMemoryHistory({ initialEntries: [path] })
-  });
-  await router.load();
-};
-
 export default createHandler(
   () => <StartServer document={...} />,
-  undefined,
-  routerLoad
+  async (context) => {
+    const url = new URL(context.request.url);
+    const path = url.href.replace(url.origin, "");
+    router.update({
+      history: createMemoryHistory({ initialEntries: [path] })
+    });
+    await router.load();
+    return {};
+  }
 );

Approach B — Restore routerLoad in solid-start

Add routerLoad back as an optional 3rd parameter to createHandler, wrapping createPageEvent to call await routerLoad(e) before rendering. Fully backward-compatible.

Diff (handler.ts):

 export function createHandler(
   fn: (context: PageEvent) => JSX.Element,
   options: HandlerOptions | ((context: PageEvent) => HandlerOptions | Promise<HandlerOptions>) = {},
-  ): H3 {
-  return createBaseHandler(createPageEvent, fn, options);
+  routerLoad?: (event: FetchEvent) => Promise<void>,
+) {
+  if (routerLoad) {
+    const _createPageEvent = createPageEvent;
+    const customCreatePageEvent = async (e: FetchEvent) => {
+      const pageEvent = await _createPageEvent(e);
+      await routerLoad(e);
+      return pageEvent;
+    };
+    return createBaseHandler(customCreatePageEvent, fn, options);
+  }
+  return createBaseHandler(createPageEvent, fn, options);
 }

Recommended addition

fresh router instance per request (applies to both A and B)

Both approaches above "work" — they were each verified with a single curl request. But the template's router.tsx exports a module-level singleton, and both fixes call router.update() + router.load() on that same shared instance per request. TanStack Router's official SSR guidance does the opposite — a fresh router per request — and for good reason: concurrency isolation.

• Official docs pass createRouter as a function (setup-ssr)
• The start-basic-nitro example exports a getRouter() factory, not a singleton (source)
• TanStack's createRequestHandler calls createRouter() once per request (createRequestHandler.ts)

Since @solidjs/start v2 (Nitro/h3) serves concurrent requests on a single event loop with no per-request serialization, two requests sharing one router instance can leak state into each other. The yield window is inside load() (where loadMatches awaits Promise.all of the route loaders), and onReady re-reads the shared store before committing — so a second request can overwrite stores.pendingMatches while the first is suspended, then the first request renders the wrong route's data.

Caveat on reproduction: this race requires async route loaders to open the yield window. The current template only has static routes with no loaders, so a single curl won't reproduce it — which is exactly why it slipped through my initial verification. In any real app that does data loading (fetch / DB / createServerFn), the structure is unsafe even though the demo passes.

The proper fix — router.tsx keeps createRouter() as a factory and drops the singleton export, and the server entry creates a fresh instance per request:

- export const router = createRouter();
+ // keep createRouter() as the factory; drop the singleton export

  // entry-server.tsx (Approach A, hardened)
- import { router } from "./router";
+ import { createRouter } from "./router";

  async (context) => {
    const path = new URL(context.request.url).href.replace(origin, "");
-   router.update({ history: createMemoryHistory({ initialEntries: [path] }) });
-   await router.load();
+   const router = createRouter();                                    // fresh per request
+   router.update({ history: createMemoryHistory({ initialEntries: [path] }) });
+   await router.load();
    return {};
  }

(Client side stays a single instance — entry-client.tsx just calls createRouter() once.)

I'd suggest rolling this router.tsx change into whichever fix PR we go with. Happy to verify the per-request version under concurrent load (e.g. wrk / ab with an async loader) if useful.

Questions for maintainers

1. Should with-tanstack-router be removed from the v2 list, or kept with a note pending the upstream fix?
2. Between Approach A (template-only) and Approach B (solid-start API restoration), which direction would you prefer?
3. Regardless of A vs B — should we also roll in the singleton → per-request router fix (the "Recommended addition" above) in the same PR?

TypeError: Cannot read properties of undefined (reading 'state')
  ...

const context = await createPageEvent(event);          // L65

const resolvedOptions =                                // L67-68
  typeof options === "function"                        //    <-- if options is async fn,
    ? await options(context)                           //    <-- awaited HERE, before render
    : { ...options };

// ... mode check ...

const html = renderToString(() => {                    // L73
  (sharedConfig.context as any).event = context;
  return fn(context);                                  // L75 <-- actual rendering
}, resolvedOptions);

Request A (/about):
  update({ history: '/about' })                         // sync
  await load()
    → beforeLoad() sync: stores.location = '/about',
                       stores.pendingMatches = [/about]  // writes shared store
    → await loadMatches() → await Promise.all(loaders)   // YIELD (load-matches.ts L1030)
Request B (/):
  update({ history: '/' })                              // sync
  await load()
    → beforeLoad() sync: stores.location = '/',
                       stores.pendingMatches = [/]       // OVERWRITES shared store
    → await loadMatches() → ...                          // YIELD
A resumes:
  → onReady: pendingMatches = stores.pendingMatches.get()  // now [/]  (router.ts L2522)
  → stores.setMatches([/])                                  // commits / data (L2569)
  → renderToString() → renders / data for the /about request  // BUG

$ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/
200

$ curl -s http://localhost:3000/ | grep -o '<title>[^<]*</title>\|Clicks: [0-9]*\|<a[^>]*>[^<]*</a>'
<title>SolidStart</title>
<a href="/">Index</a>
<a href="/about">About</a>
Clicks: 0

$ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/about
200

$ curl -s http://localhost:3000/about | grep -o 'About'
About

$ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/
200

$ curl -s http://localhost:3000/ | grep -o '<title>[^<]*</title>\|Clicks: [0-9]*\|<a[^>]*>[^<]*</a>'
<title>SolidStart</title>
<a href="/">Index</a>
<a href="/about">About</a>
Clicks: 0

$ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/about
200

Thanks!

@Tommypop2 @brenelz
I'm sorry, 64a6011
I accidentally removed it from the v1 list instead of v2, so I’ll open a follow-up PR to fix that.

Since routerLoad will be supported in the next release of solid-start, you just need to decide whether to keep or remove with-tanstack-router from the list.

To cover both cases, I’ll open PRs for both options. Please feel free to merge or close them whichever way you prefer!😅